\section{Include/RtAudio.h File Reference}
\label{_rt_audio_8h}\index{Include/RtAudio.h@{Include/RtAudio.h}}
{\ttfamily \#include $<$string$>$}\par
{\ttfamily \#include $<$vector$>$}\par
{\ttfamily \#include \char`\"{}RtError.h\char`\"{}}\par
{\ttfamily \#include $<$sstream$>$}\par
\subsection*{Classes}
\begin{DoxyCompactItemize}
\item 
class {\bf RtAudio}
\begin{DoxyCompactList}\small\item\em Realtime audio i/o C++ classes. \item\end{DoxyCompactList}\item 
struct {\bf RtAudio::DeviceInfo}
\begin{DoxyCompactList}\small\item\em The public device information structure for returning queried values. \item\end{DoxyCompactList}\item 
struct {\bf RtAudio::StreamParameters}
\begin{DoxyCompactList}\small\item\em The structure for specifying input or ouput stream parameters. \item\end{DoxyCompactList}\item 
struct {\bf RtAudio::StreamOptions}
\begin{DoxyCompactList}\small\item\em The structure for specifying stream options. \item\end{DoxyCompactList}\item 
struct {\bf CallbackInfo}
\item 
class {\bf RtApi}
\item 
struct {\bf RtApi::ConvertInfo}
\item 
struct {\bf RtApi::RtApiStream}
\item 
class {\bf RtApiDummy}
\end{DoxyCompactItemize}
\subsection*{Typedefs}
\begin{DoxyCompactItemize}
\item 
typedef unsigned long {\bf RtAudioFormat}
\begin{DoxyCompactList}\small\item\em \doxyref{RtAudio}{p.}{class_rt_audio} data format type. \item\end{DoxyCompactList}\item 
typedef unsigned int {\bf RtAudioStreamFlags}
\begin{DoxyCompactList}\small\item\em \doxyref{RtAudio}{p.}{class_rt_audio} stream option flags. \item\end{DoxyCompactList}\item 
typedef unsigned int {\bf RtAudioStreamStatus}
\begin{DoxyCompactList}\small\item\em \doxyref{RtAudio}{p.}{class_rt_audio} stream status (over-\/ or underflow) flags. \item\end{DoxyCompactList}\item 
typedef int($\ast$ {\bf RtAudioCallback} )(void $\ast$outputBuffer, void $\ast$inputBuffer, unsigned int nFrames, double streamTime, {\bf RtAudioStreamStatus} status, void $\ast$userData)
\begin{DoxyCompactList}\small\item\em \doxyref{RtAudio}{p.}{class_rt_audio} callback function prototype. \item\end{DoxyCompactList}\item 
typedef int {\bfseries ThreadHandle}\label{_rt_audio_8h_a567ef6c29f85f35ac3e0f3cb808dc6c3}

\item 
typedef int {\bfseries StreamMutex}\label{_rt_audio_8h_aee70a2c8c580d0a15b1a9a74943d41d2}

\end{DoxyCompactItemize}


\subsection{Detailed Description}


\subsection{Typedef Documentation}
\index{RtAudio.h@{RtAudio.h}!RtAudioCallback@{RtAudioCallback}}
\index{RtAudioCallback@{RtAudioCallback}!RtAudio.h@{RtAudio.h}}
\subsubsection[{RtAudioCallback}]{\setlength{\rightskip}{0pt plus 5cm}typedef int($\ast$ {\bf RtAudioCallback})(void $\ast$outputBuffer, void $\ast$inputBuffer, unsigned int nFrames, double streamTime, {\bf RtAudioStreamStatus} status, void $\ast$userData)}\label{_rt_audio_8h_a112c7b7e25a974977f6fc094cef1a31f}


\doxyref{RtAudio}{p.}{class_rt_audio} callback function prototype. 

All \doxyref{RtAudio}{p.}{class_rt_audio} clients must create a function of type RtAudioCallback to read and/or write data from/to the audio stream. When the underlying audio system is ready for new input or output data, this function will be invoked.


\begin{DoxyParams}{Parameters}
{\em outputBuffer} & For output (or duplex) streams, the client should write {\ttfamily nFrames} of audio sample frames into this buffer. This argument should be recast to the datatype specified when the stream was opened. For input-\/only streams, this argument will be NULL.\\
\hline
{\em inputBuffer} & For input (or duplex) streams, this buffer will hold {\ttfamily nFrames} of input audio sample frames. This argument should be recast to the datatype specified when the stream was opened. For output-\/only streams, this argument will be NULL.\\
\hline
{\em nFrames} & The number of sample frames of input or output data in the buffers. The actual buffer size in bytes is dependent on the data type and number of channels in use.\\
\hline
{\em streamTime} & The number of seconds that have elapsed since the stream was started.\\
\hline
{\em status} & If non-\/zero, this argument indicates a data overflow or underflow condition for the stream. The particular condition can be determined by comparison with the RtAudioStreamStatus flags.\\
\hline
{\em userData} & A pointer to optional data provided by the client when opening the stream (default = NULL).\\
\hline
\end{DoxyParams}
To continue normal stream operation, the RtAudioCallback function should return a value of zero. To stop the stream and drain the output buffer, the function should return a value of one. To abort the stream immediately, the client should return a value of two. \index{RtAudio.h@{RtAudio.h}!RtAudioFormat@{RtAudioFormat}}
\index{RtAudioFormat@{RtAudioFormat}!RtAudio.h@{RtAudio.h}}
\subsubsection[{RtAudioFormat}]{\setlength{\rightskip}{0pt plus 5cm}typedef unsigned long {\bf RtAudioFormat}}\label{_rt_audio_8h_aafca92882d25915560018873221e44b8}


\doxyref{RtAudio}{p.}{class_rt_audio} data format type. 

Support for signed integers and floats. Audio data fed to/from an \doxyref{RtAudio}{p.}{class_rt_audio} stream is assumed to ALWAYS be in host byte order. The internal routines will automatically take care of any necessary byte-\/swapping between the host format and the soundcard. Thus, endian-\/ness is not a concern in the following format definitions.


\begin{DoxyItemize}
\item {\itshape RTAUDIO\_\-SINT8:\/} 8-\/bit signed integer.
\item {\itshape RTAUDIO\_\-SINT16:\/} 16-\/bit signed integer.
\item {\itshape RTAUDIO\_\-SINT24:\/} Upper 3 bytes of 32-\/bit signed integer.
\item {\itshape RTAUDIO\_\-SINT32:\/} 32-\/bit signed integer.
\item {\itshape RTAUDIO\_\-FLOAT32:\/} Normalized between plus/minus 1.0.
\item {\itshape RTAUDIO\_\-FLOAT64:\/} Normalized between plus/minus 1.0. 
\end{DoxyItemize}\index{RtAudio.h@{RtAudio.h}!RtAudioStreamFlags@{RtAudioStreamFlags}}
\index{RtAudioStreamFlags@{RtAudioStreamFlags}!RtAudio.h@{RtAudio.h}}
\subsubsection[{RtAudioStreamFlags}]{\setlength{\rightskip}{0pt plus 5cm}typedef unsigned long {\bf RtAudioStreamFlags}}\label{_rt_audio_8h_a2c0f59b200dcec4d4e760f9166b29c41}


\doxyref{RtAudio}{p.}{class_rt_audio} stream option flags. 

The following flags can be OR'ed together to allow a client to make changes to the default stream behavior:


\begin{DoxyItemize}
\item {\itshape RTAUDIO\_\-NONINTERLEAVED:\/} Use non-\/interleaved buffers (default = interleaved).
\item {\itshape RTAUDIO\_\-MINIMIZE\_\-LATENCY:\/} Attempt to set stream parameters for lowest possible latency.
\item {\itshape RTAUDIO\_\-HOG\_\-DEVICE:\/} Attempt grab device for exclusive use.
\end{DoxyItemize}

By default, \doxyref{RtAudio}{p.}{class_rt_audio} streams pass and receive audio data from the client in an interleaved format. By passing the RTAUDIO\_\-NONINTERLEAVED flag to the openStream() function, audio data will instead be presented in non-\/interleaved buffers. In this case, each buffer argument in the RtAudioCallback function will point to a single array of data, with {\ttfamily nFrames} samples for each channel concatenated back-\/to-\/back. For example, the first sample of data for the second channel would be located at index {\ttfamily nFrames} (assuming the {\ttfamily buffer} pointer was recast to the correct data type for the stream).

Certain audio APIs offer a number of parameters that influence the I/O latency of a stream. By default, \doxyref{RtAudio}{p.}{class_rt_audio} will attempt to set these parameters internally for robust (glitch-\/free) performance (though some APIs, like Windows Direct Sound, make this difficult). By passing the RTAUDIO\_\-MINIMIZE\_\-LATENCY flag to the openStream() function, internal stream settings will be influenced in an attempt to minimize stream latency, though possibly at the expense of stream performance.

If the RTAUDIO\_\-HOG\_\-DEVICE flag is set, \doxyref{RtAudio}{p.}{class_rt_audio} will attempt to open the input and/or output stream device(s) for exclusive use. Note that this is not possible with all supported audio APIs.

If the RTAUDIO\_\-SCHEDULE\_\-REALTIME flag is set, \doxyref{RtAudio}{p.}{class_rt_audio} will attempt to select realtime scheduling (round-\/robin) for the callback thread. \index{RtAudio.h@{RtAudio.h}!RtAudioStreamStatus@{RtAudioStreamStatus}}
\index{RtAudioStreamStatus@{RtAudioStreamStatus}!RtAudio.h@{RtAudio.h}}
\subsubsection[{RtAudioStreamStatus}]{\setlength{\rightskip}{0pt plus 5cm}typedef unsigned long {\bf RtAudioStreamStatus}}\label{_rt_audio_8h_a80e306d363583da3b0a1b65d9b57c806}


\doxyref{RtAudio}{p.}{class_rt_audio} stream status (over-\/ or underflow) flags. 

Notification of a stream over-\/ or underflow is indicated by a non-\/zero stream {\ttfamily status} argument in the RtAudioCallback function. The stream status can be one of the following two options, depending on whether the stream is open for output and/or input:


\begin{DoxyItemize}
\item {\itshape RTAUDIO\_\-INPUT\_\-OVERFLOW:\/} Input data was discarded because of an overflow condition at the driver.
\item {\itshape RTAUDIO\_\-OUTPUT\_\-UNDERFLOW:\/} The output buffer ran low, likely producing a break in the output sound. 
\end{DoxyItemize}